API Responses

All API responses are returned in JSON format.

Success Response

{
  "data": {
    "id": 123,
    "name": "Example Account",
    "type": "asset"
  },
  "status": "success"
}

Error Response

{
  "error": {
    "message": "Resource not found",
    "code": 404
  },
  "status": "error"
}

HTTP Status Codes

The Qoyod API uses standard HTTP status codes to indicate the success or failure of requests:

Status Code	Meaning	Description
200	OK	Request succeeded
201	Created	Resource successfully created
400	Bad Request	Invalid request parameters or format
401	Unauthorized	Missing or invalid API key
404	Not Found	Resource does not exist
422	Unprocessable Entity	Validation errors in request data
429	Too Many Requests	Rate limit exceeded
500	Internal Server Error	Server-side error occurred

Error Handling Best Practices

Implement robust error handling in your integration:

const makeQoyodRequest = async (endpoint, options = {}) => {
  const maxRetries = 3;
  let attempt = 0;

  while (attempt < maxRetries) {
    try {
      const response = await fetch(
        `https://api.qoyod.com/v1${endpoint}`,
        {
          ...options,
          headers: {
            'API-KEY': process.env.QOYOD_API_KEY,
            'Content-Type': 'application/json',
            ...options.headers
          }
        }
      );

      if (response.status === 429) {
        // Rate limited - wait and retry
        const retryAfter = response.headers.get('Retry-After') || 60;
        await sleep(retryAfter * 1000);
        attempt++;
        continue;
      }

      if (!response.ok) {
        const error = await response.json();
        throw new Error(`API Error: ${error.error.message}`);
      }

      return await response.json();
    } catch (error) {
      if (attempt === maxRetries - 1) throw error;
      
      // Exponential backoff
      await sleep(Math.pow(2, attempt) * 1000);
      attempt++;
    }
  }
};

const sleep = (ms) => new Promise(resolve => setTimeout(resolve, ms));